home *** CD-ROM | disk | FTP | other *** search
/ The X-Philes (2nd Revision) / The X-Philes Number 1 (1995).iso / xphiles / psion / fileio < prev    next >
Text File  |  1995-03-31  |  13KB  |  293 lines

  1. PSIONICS FILE - FILEIO
  2. ======================
  3. Filing system IO interfaces
  4. Last modified 1994-09-16
  5. ===========================
  6.  
  7. This document describes the use of the IO interface for accessing the filing
  8. system. For general discussion on IO, see the Psionics file DEVICES.
  9.  
  10. The filing system is a special device driver, called "FIL:". Whenever an open
  11. fails to locate a device, or if the name opened is not that of a device driver,
  12. the driver name "FIL:" is prefixed, and the open is retried. Thus the original
  13. name becomes the channel name. For file IO, the channel name is, or controls,
  14. the file name.
  15.  
  16. An addition filing system called "TXT:" also exists. This is identical to
  17. "FIL:", and accesses the same files, except that all files are assumed to
  18. be text files (see below). There is no normal need to use "TXT:"; instead,
  19. use "FIL:" and open files with a format component of 2 (see below).
  20.  
  21.  
  22. Filing system organisation
  23. --------------------------
  24.  
  25. The filing system is divided into one or more nodes. A node has a name ending
  26. with a double colon. The nodes most commonly met are:
  27.   "LOC::"  files in the internal ram and on attached SSDs and 3-Link pods
  28.   "REM::"  files accessed via the 3-Link (not the 3-Link pod itself)
  29.   "ROM::"  files in the internal rom
  30.  
  31. A node may be monolithic, or may be divided into devices. The devices available
  32. and the format of their names depends on the node. For example:
  33.   LOC::  devices are usually "M:", "A:", "B:", and possibly "C:".
  34.   REM::  device names depend on the remote system
  35.   ROM::  monolithic
  36. Unless explicitly stated otherwise, the term device includes monolithic nodes.
  37.  
  38. A node may be flat or hierarchical. In the former case, each device is a single
  39. directory which contains files. In the latter, each device has a directory
  40. hierarchy starting with a root directory; each directory can hold files and
  41. other directories.
  42.  
  43. The format of file and directory names depends on the node. Various system
  44. calls (such as FilChangeDirectory) can be used to manipulate file names. The
  45. LOC:: node uses \ as a directory name terminator (the root directory is just
  46. called "\"), and allows both file and directory names to consist of up to 8
  47. characters, a dot, and then up to 3 characters. The ROM:: node is flat, and
  48. uses the same rules for file names.
  49.  
  50. The full pathname of a file consists of the node, the device (if any), the path
  51. of directories (if any), and the filename, all joined with no intervening
  52. spaces. It is limited to 128 characters.
  53.  
  54. The system has the concept of a current path. When any filename does not
  55. include a filing system, device, or directory, that of the current path is
  56. used. For example, if the current path is "LOC::A:\APP\", then the names
  57. "XXX\YYY", "REM::\QQQ", and "M:ZZZ" actually refer to "LOC::A:\APP\XXX\YYY",
  58. "REM::A:\QQQ", and "LOC::M:\APP\ZZZ".
  59.  
  60.  
  61. Opening files
  62. -------------
  63.  
  64. There are two kinds of open: open for scanning, and open for access. These
  65. are both done with the IOOPEN keyword, but once the file is open, it is used
  66. in totally different ways.
  67.  
  68.  
  69. Opening for scanning
  70. --------------------
  71.  
  72. A file is opened for scanning by specifying one of the following modes to
  73. IOOPEN:
  74.     $0030 = scan a directory
  75.     $0050 = scan a node
  76.     $0060 = scan all nodes
  77.     $0040 = format a device
  78.     $8040 = format a device in low density
  79.  
  80. In each case, once the file is opened, it is scanned or formatted by making
  81. several calls to function 1 until one fails with error -36 (end of file).
  82. [Note: the IOREAD keyword should be equivalent to function 1. However, there
  83. have been reports of problems with using it.] Once a call fails, the handle
  84. should be closed. All these calls will ignore the length variable (argument 2).
  85.  
  86. Scanning generates a list of names. There are three different scans that can
  87. be done:
  88. * Scan all nodes; the name opened is ignored (and so would normally be "FIL:"),
  89.   and a list of all the available nodes is returned.
  90. * Scan a node; the node is extracted from the name opened, and a list of all
  91.   devices on that node is returned.
  92. * Scan a directory; the name opened should either identify a directory (on
  93.   the LOC:: node, this is done by having it end with a backslash), or should
  94.   contain wildcards in the filename part. [If neither of these is true, only
  95.   the original name will normally be returned; "A:" counts as a directory for
  96.   these purposes.] A list of all names in the directory, or all matching names,
  97.   is returned.
  98.  
  99. One member of the list is returned, as a cstr, by each call to function 1. The
  100. buffer (argument 1) should be at least 128 bytes long.
  101.  
  102.  
  103. Formatting is used to prepare a device to contain files and to erase any
  104. previous contents. If a device supports multiple densities, it can be formatted
  105. at normal or low density. The node and device part of the name identifies the
  106. device to format; the remainder, if any, specifies a new volume name for the
  107. device (otherwise the previous one is reused).
  108.  
  109. The first call to function 1 will write a count into the first word of the
  110. buffer (argument 1); subsequent calls will ignore the buffer. This first call
  111. will not alter the device, and if the handle is closed immediately afterwards,
  112. nothing will happen. Otherwise, the count indicates the number of subsequent
  113. calls required to format the device. If the handle is closed before that number
  114. of calls has been made, the device will be left in an unusable state; it can
  115. be recovered by reformatting, but any information normally transferred to a
  116. reformatted device, such as the previous volume name or the unique serial
  117. number, will be lost.
  118.  
  119. As an example, when formatting a 2Mb flash SSD, the format count was 513. This
  120. consisted of:
  121. * 256 calls which each wrote all zeroes to 8192 bytes of the card, starting
  122.   at address 0.
  123. * 8 blocks of 32 calls; the first call in each block restored 256 kbytes to
  124.   all $FF, and the other 31 did nothing.
  125. * A final call which restored the initial area of the card (serial number,
  126.   volume name, empty root directory, etc.).
  127.  
  128.  
  129. Opening for access
  130. ------------------
  131.  
  132. A file is opened for access in order to read or write the file. To open a file
  133. for access, the mode parameter to IOOPEN has the following value:
  134.     Bits 0 to 3: (service component)
  135.       0 = open an existing file
  136.       1 = create a new file
  137.       2 = replace an existing file
  138.       3 = open a file for appending only
  139.       4 = open a new file with an existing name
  140.     Bits 4 to 7: (format component)
  141.       0 = open a binary file for stream access
  142.       1 = open a binary file for text access
  143.       2 = open a text file for text access
  144.     Bit  8: allow writing
  145.     Bit  9: allow random access
  146.     Bit 10: allow shared access
  147. These individual components are now described.
  148.  
  149.  
  150. Service component
  151. -----------------
  152.  
  153. The service component indicates what to do with the existing contents of the
  154. file. There are five possibilities:
  155. * 0 and 3 open an existing file, leaving the content unchanged. They differ
  156.   only in the setting of the current position (0 = start, 3 = end). If the
  157.   file does not exist, the open fails.
  158. * 1 and 2 will create the file if it does not exist; 1 will fail if the file
  159.   does already exist, while 2 will succeed. After opening, the file will
  160.   be empty (length 0), and so the current position will be at both the start
  161.   and end of the file.
  162. * 4 is equivalent to 1, but with a new file name. The file name passed is
  163.   examined to determine the directory, and a new file is created in that
  164.   directory; the resulting name overwrites the passed name. If the IOOPEN
  165.   keyword is used, the name parameter is replaced by ADDR(qstr), as explained
  166.   in the OPL manual. If the IoOpen system call is used, the name (a cstr) is
  167.   passed in the same way as for other modes, and will be overwritten; there
  168.   should thus be room for 128 bytes.
  169.  
  170.  
  171. Format component
  172. ----------------
  173.  
  174. There are two kinds of file: text and binary. A text file consists of a
  175. sequence of records, each ending with a newline character, while a binary
  176. file consists of arbitrary data, which is not broken into records.
  177.  
  178. Each node has its own way of storing text and binary files. On some nodes,
  179. the two types are completely distinct. On others, text files are merely a way
  180. of interpreting binary files. This is the case for the LOC:: and ROM:: nodes.
  181. In either case, a record in a text file is limited to 256 bytes, and may not
  182. contain $0A, $0D, or $1A.
  183.  
  184. In the LOC:: and ROM:: nodes, a text file obeys the following rules:
  185. * Each of the following sequences marks the end of a record:
  186.     $0A $0D $1A
  187.     $0A $1A
  188.     $0A
  189.     $0D $0A $1A
  190.     $0D $1A
  191.     $0D
  192.     $1A
  193.   In each case, the longest applicable sequence is used. These bytes are not
  194.   part of the record.
  195. * Anything after a $1A byte (including one in a record terminator) is ignored.
  196.  
  197. The three access modes are used to determine the way the file is processed.
  198. * Mode 0 opens a binary file for binary access.
  199. * Mode 1 opens a text file for binary access.
  200. * Mode 2 opens a text file for text access.
  201. The meaning of each of these is discussed below, under reading and writing.
  202. If a node does not distinguish binary and text files, the contents of the file
  203. are treated in the way described above. If it does distinguish them, the open
  204. will fail if the file has the wrong type.
  205.  
  206.  
  207. Other opening flags
  208. -------------------
  209.  
  210. If the "writing" flag is not set on opening, all attempts to alter the file
  211. will fail. This includes files created by the open function.
  212.  
  213. If the "random access" flag is not set on opening, all attempts to set the
  214. current position (as opposed to altering it by reading and writing) will fail.
  215.  
  216. If the "shared" flag is not set on opening, the file is locked, and no other
  217. process may open it until this one closes it. If the flag is set, the file
  218. is open for sharing; other processes may also open it for sharing, but none
  219. of the processes may alter to the file.
  220.  
  221.  
  222. Reading and writing
  223. -------------------
  224.  
  225.  
  226. When reading or writing a binary file, the requested data is transferred
  227. directly without change. Up to 16k can be read or written with one call. On
  228. a read, the length argument is changed to the actual number of bytes read. The
  229. data is read from or written at the current position, which is moved to the
  230. end of that data.
  231.  
  232. When reading a text file as binary, the file is treated exactly as if each
  233. record were followed by $0D $0A; partial records can be read into the buffer,
  234. and the remaining portion will be retained until the next read.
  235.  
  236. When writing a text file as binary, the following sequences of bytes are taken
  237. to mark the end of a record:
  238.     $0A $0D
  239.     $0A
  240.     $0D $0A
  241.     $0D
  242. Again, in each case the longest applicable sequence is used, and these bytes
  243. are not written as part of the record.
  244.  
  245. In all other respects access to a text file as binary behaves the same as
  246. access to a binary file.
  247.  
  248. When reading a text file as text, exactly one record is read from the file into
  249. the buffer; no explicit end-of-record marker is added. If the record is larger
  250. than the buffer, the trailing data is ignored and error -43 is returned. The
  251. length argument is changed to the number of bytes placed in the buffer. The
  252. record is read from the current position, which is moved to the start of the
  253. next record. Since text records are limited to 256 bytes, no more than that
  254. can ever be read.
  255.  
  256. When writing a text file as text, the contents of the buffer are written as a
  257. single record at the end of the file, no matter what the current position. The
  258. current position is moved to the end of the file. Records are limited to 256
  259. bytes, and must not contain $0A, $0D, or $1A.
  260.  
  261. When writing to a flash SSD, there is one special case: if the write is a
  262. single byte, and if every bit of that byte is left unchanged or changes from
  263. 1 to 0 [equivalently, if (old AND new) = new], then the byte will be modified
  264. in situ. In all other cases, the old data will remain in place, but the file
  265. structure will be modified to skip it and point to the new data instead.
  266.  
  267.  
  268. Other IO functions
  269. ------------------
  270.  
  271. Function:   9
  272. Argument 1: unused
  273. Argument 2: unused
  274.  
  275. Any buffered data is written to the file, and the file's modification date is
  276. updated if necessary. On the LOC:: node, the only buffering done for binary
  277. files is of the modification date of files on flash. Text files are buffered.
  278.  
  279.  
  280. Function:   11
  281. Argument 1: (long) new filesize
  282. Argument 2: unused
  283.  
  284. If the file is shorter than the specified length, random data is appended to
  285. bring it to that length; the current position is unaltered. If it is longer,
  286. the file is truncated to that length, and the current position is set to the
  287. new end of file.
  288. -- 
  289. Clive D.W. Feather     | Santa Cruz Operation    | If you lie to the compiler,
  290. clive@sco.com          | Croxley Centre          | it will get its revenge.
  291. Phone: +44 1923 813541 | Hatters Lane, Watford   |   - Henry Spencer
  292. Fax:   +44 1923 813811 | WD1 8YN, United Kingdom | <= NOTE: NEW PHONE NUMBERS
  293.